<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
	<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=utf-8">
	<TITLE>XML format for schema description</TITLE>
	<META NAME="GENERATOR" CONTENT="LibreOffice 3.5  (Linux)">
	<META NAME="AUTHOR" CONTENT="Viacheslav Naydenov">
	<META NAME="CREATED" CONTENT="20130520;10080300">
	<META NAME="CHANGEDBY" CONTENT="Vaclav Naydionov">
	<META NAME="CHANGED" CONTENT="20140601;16544300">
	<STYLE TYPE="text/css">
	<!--
		@page { margin: 2cm }
		P { margin-bottom: 0.21cm }
		H2 { margin-bottom: 0.21cm }
		H2.western { font-family: "Times New Roman", serif }
		H2.cjk { font-family: "Droid Sans Fallback" }
		H2.ctl { font-family: "Lohit Hindi" }
		TT.western { font-family: "Courier New", monospace }
		TT.cjk { font-family: "Droid Sans Fallback", monospace }
		TT.ctl { font-family: "Lohit Hindi", monospace }
	-->
	</STYLE>
</HEAD>
<BODY LANG="en-US" DIR="LTR">
<H2 CLASS="western">XML format for schema description</H2>
<P>See also files <TT CLASS="western">*.xml</TT> in the <TT CLASS="western">examples</TT>
folder.</P>
<P>The root element of the schema description document is <TT CLASS="western">&lt;schema&gt;</TT>.
It can have nested elements <TT CLASS="western">&lt;table&gt;</TT>
and <TT CLASS="western">&lt;relation&gt;</TT>.</P>
<P>To describe an entity (a table) and to map it to a class use
<TT CLASS="western">&lt;table&gt;</TT> element. In turn, it contains
one or more nested <TT CLASS="western">&lt;column&gt;</TT> elements
to describe a single table column and to map it to object data
member. The following attributes for <TT CLASS="western">&lt;table&gt;</TT>
element are accepted:</P>
<UL>
	<LI><P><TT CLASS="western">name</TT> – The name of table, provide
	as in SQL. This is a <EM>required</EM> attribute.</P>
	<LI><P><TT CLASS="western">class</TT> – The name of class to map
	the table to, if not set no domain class will be created for the
	table.</P>
	<LI><P><TT CLASS="western">sequence</TT> – To be able to generate
	unique IDs for newly inserted records some databases (Oracle,
	Postgres) utilize sequences or generators, some others (e.g. MySQL)
	– don't. You can safely set here the name of sequence that will be
	used to generate IDs if the underlying database supports this; for
	other databases this will mean that the value for the primary key in
	the table is auto-generated on insertion.</P>
	<LI><P><TT CLASS="western">autoinc</TT> – Like the previous, but
	only suitable for databases with no sequences or generators, like
	MySQL and SQLite. The value of this attribute is ignored.</P>
	<LI><P><TT CLASS="western">xml-name</TT> – The name will be used
	when a persistent object is serialized in form of XML (look at
	<TT CLASS="western">include/yb/orm/xmlizer.h</TT>). If not given the
	table's name is used, translated to lower case, where all <TT CLASS="western">&quot;_&quot;</TT>
	are replaced with <TT CLASS="western">&quot;-&quot;</TT>.</P>
</UL>
<P>Use element <TT CLASS="western">&lt;column&gt;</TT> to describe a
column/class data member. This element may have the following
attributes:</P>
<UL>
	<LI><P><TT CLASS="western">name</TT> – The name of column, provide
	as in SQL. This is a <EM>required</EM> attribute.</P>
	<LI><P><TT CLASS="western">property</TT> – The name of class
	member if it must differ from column's name.</P>
	<LI><P><TT CLASS="western">type</TT> – The data type of the
	column. This is a <EM>required</EM> attribute. YB.ORM has its own
	set of types, and they are mapped both to SQL types, taking into
	account dialect specifics, and to C++ types. As of now, the
	following data types are supported:</P>
	<UL>
		<LI><P><TT CLASS="western">&quot;string&quot;</TT> – String of
		text characters.</P>
		<LI><P><TT CLASS="western">&quot;integer&quot;</TT> – 32-bit
		signed integer.</P>
		<LI><P><TT CLASS="western">&quot;longint&quot;</TT> – 64-bit
		signed integer, suitable for ID generation.</P>
		<LI><P><TT CLASS="western">&quot;decimal&quot;</TT> – Precise
		decimal number with fraction part, suitable for storing money
		values, etc.</P>
		<LI><P><TT CLASS="western">&quot;float&quot;</TT> – Double
		precision floating point number.</P>
		<LI><P><TT CLASS="western">&quot;datetime&quot;</TT> – Time stamp
		with date and time parts.</P>
	</UL>
	<LI><P><TT CLASS="western">size</TT> – The maximum length of the
	value in that column, applicable to <TT CLASS="western">&quot;string&quot;</TT>
	type columns only.</P>
	<LI><P><TT CLASS="western">null</TT> – The flag denotes the column
	that may be assigned <TT CLASS="western">NULL</TT>, the possible
	values are <TT CLASS="western">&quot;true&quot;</TT> and <TT CLASS="western">&quot;false&quot;</TT>.
	By default it's <TT CLASS="western">&quot;true&quot;</TT> unless the
	column is marked to be a (part of) primary key, see below.</P>
	<LI><P><TT CLASS="western">default</TT> – The option sets the
	default value for the column. This attribute may contain a constant
	of type, specified by the <TT CLASS="western">type</TT> attribute,
	or a special value <TT CLASS="western">&quot;sysdate&quot;</TT>
	suitable for <TT CLASS="western">&quot;datetime&quot;</TT> type
	columns. In latter case the current time will be used as the default
	when a record is created.</P>
	<LI><P><TT CLASS="western">xml-name</TT> – The name will be used
	when a persistent object is serialized in form of XML (look at
	<TT CLASS="western">include/yb/orm/xmlizer.h</TT>), if not given the
	column's name is used, translated to lower case, where all <TT CLASS="western">&quot;_&quot;</TT>
	are replaced with <TT CLASS="western">&quot;-&quot;</TT>. To exclude
	a column from the serialized representation of the object set this
	field to special value <TT CLASS="western">&quot;!&quot;</TT>.</P>
</UL>
<P>The following nested elements may be found inside a <TT CLASS="western">&lt;column&gt;</TT>
element, they describe additional constraints:</P>
<UL>
	<LI><P><TT CLASS="western">&lt;read-only&gt;</TT> – The column may
	only be assigned a value on selection from database or on object
	creation, any subsequent updates will produce an error.</P>
	<LI><P><TT CLASS="western">&lt;primary-key&gt;</TT> – Mark the
	column as a primary key or as a part of compound primary key.</P>
	<LI><P><TT CLASS="western">&lt;foreign-key&gt;</TT> – The column
	references to another table and column, this is also known as
	foreign key constraint. To describe the reference this element is
	given the following attributes:</P>
	<UL>
		<LI><P><TT CLASS="western">table</TT> – The name of the table the
		column references. This is a <EM>required</EM> attribute.</P>
		<LI><P><TT CLASS="western">key</TT> – The column name in the
		referenced table. This may be omitted if the column referenced is
		the primary key.</P>
	</UL>
</UL>
<P>To describe a relationship between domain classes use a top-level
element <TT CLASS="western">&lt;relation&gt;</TT>. The contents of
this element depends on the type of the relationship, that can be set
using a required attribute <TT CLASS="western">type</TT>. As of now,
the only accepted value for that attribute is <TT CLASS="western">&quot;one-to-many&quot;</TT>.
Other kinds of relationships (e.g. <TT CLASS="western">&quot;many-to-many&quot;</TT>,
<TT CLASS="western">&quot;parent-to-child&quot;</TT>) are yet to be
implemented. The optional attribute <TT CLASS="western">cascade</TT>
defines what action to take for the slave records on an attempt to
delete the master record. Possible actions are the following.</P>
<UL>
	<LI><P><TT CLASS="western">&quot;restrict&quot;</TT> – Deny to
	delete the parent.</P>
	<LI><P><TT CLASS="western">&quot;set-null&quot;</TT> – Set to <TT CLASS="western">NULL</TT>
	the foreign key column in all the child records. To use <TT CLASS="western">&quot;set-null&quot;</TT>
	the dependent table must have its foreign key column marked as
	nullable: <TT CLASS="western">null=&quot;true&quot;</TT>.</P>
	<LI><P><TT CLASS="western">&quot;delete&quot;</TT> – Cascade
	delete all the child records.</P>
</UL>
<P>For <TT CLASS="western">&quot;one-to-many&quot;</TT> kind of
relationship there are always two sides, each described by one of two
required nested elements: <TT CLASS="western">&lt;one&gt;</TT> or
<TT CLASS="western">&lt;many&gt;</TT>. The former refers to the
master table and class, and the latter refers to the dependent
(slave) table and its class. Element <TT CLASS="western">&lt;one&gt;</TT>
may have the following attributes:</P>
<UL>
	<LI><P><TT CLASS="western">class</TT> – The class name, mapped to
	the master table. This is a <EM>required</EM> attribute.</P>
	<LI><P><TT CLASS="western">property</TT> – The name of the
	property that is added to the master class to reference (typically
	multiple) dependent objects. This is a <EM>collection</EM> property
	unless attribute <TT CLASS="western">use-list</TT> specifies the
	opposite case. If not specified – no property is added to the
	master class for that relationship.</P>
	<LI><P><TT CLASS="western">use-list</TT> – If there is a property
	at the master object, referencing its slave objects, then this
	attribute set to <TT CLASS="western">&quot;false&quot;</TT>
	instructs to add a <EM>single object</EM> reference property rather
	than a collection property. This is particularly useful for modeling
	relationships of <TT CLASS="western">&quot;one-to-one&quot;</TT>
	kind.</P>
</UL>
<P>Element <TT CLASS="western">&lt;many&gt;</TT> for the dependent
class may have the following attributes:</P>
<UL>
	<LI><P><TT CLASS="western">class</TT> – The class name, mapped to
	the dependent table. This is a <EM>required</EM> attribute.</P>
	<LI><P><TT CLASS="western">property</TT> – The name of the
	property added to the dependent class to reference its master
	object.</P>
	<LI><P><TT CLASS="western">key</TT> – The attribute specifies what
	column to use as a foreign key, may be useful if there's more than
	one relationship between the two tables.</P>
	<LI><P><TT CLASS="western">order-by</TT> – Here you can put an SQL
	expression for <TT CLASS="western">ORDER BY</TT> clause to determine
	the order in which dependent objects will be selected, e.g. when
	walking through the collection property at the master object side.</P>
</UL>
</BODY>
</HTML>